Repository navigation
Conversation
The posthog-node/nodemailer entry point exports createPostHogTransport({ client, defaultTemplateKey }). Pass it to nodemailer.createTransport() and every sendMail call sends one PostHog email through the client's emails.send, marked nodemailer/<version>. PostHog's options ride in sendMail({ posthog: { ... } }). A message PostHog can't carry fails with code EPOSTHOGUNSUPPORTED before any request, and a failed send says whether a retry with the same idempotency key can succeed. Nodemailer stays a dev dependency.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Coherence📄 0 spec file errors · ⛔ 0 broken rules · 🚪 2 unchecked inputs · 🐛 0 bugs that came back What is Coherence?Coherence compares the code with its spec files ( This check read 44 parts of the code and 7 rules. Note These findings do not make this check fail. None of these findings are in files that this pull request changes. You do not need to fix them in this pull request. 🚪 Unchecked inputs (2)
What this means and how to fix itInput from outside this code comes in at these places. The spec does not say what checks that input. 10 more places were already like this when Coherence was added. This list does not show them. To close one of these, find the place by its name in the
To get the line to add, run |
There was a problem hiding this comment.
PostHog Review · Standard · reviewed d1d5353: 6 Should fix, 1 Consider.
See this review and its findings in PostHog Review. Comment @posthog review --deep for a Deep review. A Deep review takes longer and looks deeper than a Standard review.
Node SDK acceptance v2Commit: 4cf1529 Capture v0✅ 83 passed / ❌ 4 non-passing / Drill-down: run artifacts → ❌ server_snapshot_payload_false — failed_assertionExpected native data result Code: Failed step: acceptance/public/evaluate-flags.feature:868 the public snapshot outcomes should have these semantics: ❌ server_snapshot_payload_zero — failed_assertionExpected native data result Code: Failed step: acceptance/public/evaluate-flags.feature:868 the public snapshot outcomes should have these semantics: ❌ server_snapshot_payload_null — failed_assertionExpected native data result Code: Failed step: acceptance/public/evaluate-flags.feature:868 the public snapshot outcomes should have these semantics: ❌ migration/yaml-parity-v1/remote-flags-v1.feature::Omitted GeoIP settings default to enabled in flag requests — failed_assertionFlags field differs Code: Failed step: migration/yaml-parity-v1/remote-flags-v1.feature:134 the first flags request field "geoip_disable" should equal JSON false Operation: Field: Expected: false Actual value: true Harness exit: 1; report validation exit: 1. Capture v1✅ 148 passed / ❌ 4 non-passing / Drill-down: run artifacts → ❌ server_snapshot_payload_false — failed_assertionExpected native data result Code: Failed step: acceptance/public/evaluate-flags.feature:868 the public snapshot outcomes should have these semantics: ❌ server_snapshot_payload_zero — failed_assertionExpected native data result Code: Failed step: acceptance/public/evaluate-flags.feature:868 the public snapshot outcomes should have these semantics: ❌ server_snapshot_payload_null — failed_assertionExpected native data result Code: Failed step: acceptance/public/evaluate-flags.feature:868 the public snapshot outcomes should have these semantics: ❌ migration/yaml-parity-v1/remote-flags-v1.feature::Omitted GeoIP settings default to enabled in flag requests — failed_assertionFlags field differs Code: Failed step: migration/yaml-parity-v1/remote-flags-v1.feature:134 the first flags request field "geoip_disable" should equal JSON false Operation: Field: Expected: false Actual value: true Harness exit: 1; report validation exit: 1. |
…ransport for createTransport
An attachment's raw source and an attachment's own headers are refused, so PostHog never sends other bytes or loses a Content-ID. Headers passed as a list of { key, value } are read by name. The transport's normalize data is unknown to TypeScript, so createTransport() picks the transport overload and a send resolves to { messageId }. Base64 attachment content from normalize() goes to the SDK as it is.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…nodemailer-transport
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
# Conflicts: # packages/node/package.json # pnpm-lock.yaml
… tracking through Refuse every message option the transport doesn't carry, rather than a list of known ones: Nodemailer's OTP-Token header, REQUIRETLS, DKIM, and MIME changes from stream plugins now fail with EPOSTHOGUNSUPPORTED instead of sending without them. Compare envelope mailboxes by their exact local part, refuse a raw HTML or text source, refuse Content-* headers PostHog doesn't set itself, send a missing subject as an empty one, and give up on a message whose streams stall. The posthog slot takes tracking and sensitive in place of capture_engagement, and NodeNext ESM consumers get the slot's types too. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
SDK performance: posthog-nodeBenchmarks completed. No changes flagged for review. Flags require at least a 5% change in the median and all six pairs agreeing on direction. This is a noise filter, not proof of a performance change or a CI gate. View all results
Values are medians of paired measurements. Not flagged does not mean unchanged. Unavailable means a measurement could not be provided, not zero. Estimated allocation measurements retain their instrumentation uncertainty. RSS measures the whole process, not just SDK allocations; observed peaks are sampled checkpoints. Paired ranges in the diagnostics describe variability, not confidence intervals. Each shard uses its own runner; compare Before PR against With PR within a row, not across shards. Compared 102 metric rows; 102 rows shown in all results. Omitted or shortened data remain in |
…n' into map41/nodemailer-transport
…ries safe - Refuse a message when a stream plugin is registered, since it changes MIME that PostHog doesn't send. - Refuse headers on the html and text parts. - Check the envelope only when the message sets its own, so a message without from that has a reply-to sends. - Say a network error or an in-flight key is retryable only when the message has an idempotency key. - Give data URL images stable content IDs, so a retry with the same key replays. - Keep the read deadline referenced, so a script waits for the send to fail. Ticket: PostHog/michaelr-context#41 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Note 🤖 Claude Opus 5.5 responding on behalf of Michael Decisions from review rounds 1 (fixed in 5eef616) and 2 (fixed in c9a28bd), and the final reads (fixed in 38baa70 and 4cf1529):
|
…ata URL content IDs apart A message without posthog.idempotency_key is not retryable on any failure, since an earlier attempt of the send may have queued it. Renumbered data URL content IDs skip any content ID the message sets itself. The process test waits for the send to start before it checks the script stays alive. Refs PostHog/michaelr-context#41 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A longer content ID that starts with Nodemailer's generated one kept a rewritten prefix in the HTML and lost its image. Refs PostHog/michaelr-context#41 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A srcset comma or an encoded quote in a CSS url left the reference on the old content ID, so the renamed image broke. Refs PostHog/michaelr-context#41 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Problem
A Node app that sends email with Nodemailer can't send that email through PostHog without rewriting every
sendMailcall asposthog.emails.send().Ticket: https://github.com/PostHog/michaelr-context/issues/41 (private).
Stacked on #5574, which is stacked on #5514. Merge them first. This PR stays a draft until the email SDKs release.
Seams for review. The
integrationoption from #5574 is a seam: the Convex sender in #5579 stacks on it too, and PostHog/posthog#130017 reads the name before the/of a validX-PostHog-Integrationheader as the send'sclient. The posthog.com page for the transport is PostHog/posthog.com#21987. Check for cross-stack breaks: a marker pattern that the server reads differently, the same concept built twice, or a header that one stack sets and another doesn't read.Impact
Shows on the
clientproperty that PostHog/posthog#130017 adds to thetransactional email api sendevent: weekly organizations whose code sends come fromnodemailer. Success: Nodemailer sends appear there after the email SDKs release, from teams that already send with Nodemailer.Merge danger
Warning
🟡 Merge risk: medium, 🔴 at release · one-way door once posthog-node releases: the
posthog-node/nodemailerentry point, itsposthogoptions and its refusal codesposthog-node/nodemailersends each message as oneemails.send(), or gets anEPOSTHOGUNSUPPORTEDrefusal before any request. The merge lands on a stack branch and no released package carries it, so no traffic takes it until the release; the grade is medium because the diff adds more than 400 production lines while a row stays uncovered.posthog-nodestill loads and sends without Nodemailer installed (nodemailer-absent.spec.tson the built package), and the SDK's own send path changes only by theisRetryableexport.fetchandFakePostHog; a mapping bug they miss would send other content than the app asked for, without an error, to the Nodemailer teams that opt in.normalize(), as Nodemailer's JSON and SES transports do, before the SDK's 10-file and 40 MB check. A stalled stream of the app's fails withETIMEDOUTafter 60 seconds and is closed; a URL ends within Nodemailer's own fetch limits.posthog-node/nodemailer)Rollout
transactional email api sendevents withclient = nodemailer. No alert pages on this path.Changes
createPostHogTransport({ client, defaultTemplateKey? })returns a Nodemailer transport,{ name, version, send(mail, done) }. It reads each message withmail.normalize(), within 60 seconds, or fails withETIMEDOUT. It doesn't import Nodemailer at run time, soposthog-nodeandposthog-node/nodemailerload when Nodemailer isn't installed.emails.send(), withintegration: 'nodemailer/<posthog-node version>'(from feat(node): let an integration name itself on an email send #5574). The SDK still does the checks, the uploads, the request, the retries, and the idempotency key. Attachments, inline images, and data URL images go through the SDK's upload. The content IDs Nodemailer generates for data URL images are renumbered in order, skipping any the message sets itself, so a retry maps to the same send. Only wholecid:references change, so a longer content ID that starts with a generated one keeps its name, and a reference in asrcsetor a CSSurl("…")changes too.sendMail({ posthog: { distinct_id, template_key, idempotency_key, tracking, sensitive } }).trackingtakestrue,false, or{ opens, clicks }, andsensitivepasses through; there is nocapture_engagement. In TypeScript, the entry point addsposthogto Nodemailer's message options, in CommonJS and in NodeNext ESM consumers. The template key isposthog.template_key, thendefaultTemplateKey, thennodemailer.Errorthat hascode: 'EPOSTHOGUNSUPPORTED'and arefusal:multiple_to,unsupported_header,unsupported_part,unsupported_priority,unsupported_option,envelope_mismatch,inline_without_cid, orinvalid_template_key. That covers headers and parts PostHog doesn't send, raw MIME, an envelope of the message's own that names other people, a registered stream plugin or DKIM, and any message option the transport doesn't know. PostHog never sends part of a message.Errorthat hascode,status,detail,attr,retryable, andretry_after(seconds), with the SDK'sEmailErroras itscause. It isretryableonly when the message hasposthog.idempotency_keyand the SDK would retry the failure: without a key, an earlier attempt may have queued the message, so a retry could send a second copy.isRetryableis now exported inside the package for this.done(null, { messageId })with PostHog's message ID.Evidence
vitest runfor posthog-node): green, 54 files, 1882 tests. It ran throughfleet heavyon the devbox because the worktree box didn't start. CI on this PR: see below, because the base isn'tmain.nodemailer.createTransport(createPostHogTransport(...))andsendMail(), through the real SDK, withfetchstubbed, and withFakePostHogfor files.X-PostHog-IntegrationandUser-Agentheaders. That is every rendered send, display names, cc, bcc and reply-to, theposthogoptions with tracking and sensitive, the default template key, the ignored headers, and an envelope that names the same people.watchHtml, alternatives, raw MIME on the message, the HTML or an attachment, headers on the HTML, text or an attachment, a high priority,inReplyTo,list,otp, asenderthat isn'tfrom, REQUIRETLS, DKIM, an unknown option, and stream plugins that transform, process, or set a header.FakePostHog: case 04 with an inline image, a text file and a stream, and a retry of a message with data URL images that replays, a data URL image next to an image whose content ID the message sets to the same name the renumbering would pick, a longer content ID that starts with a generated one, and generated references in asrcsetand a CSSurl("…").Retry-After), 500, 503, and a network error, with an idempotency key, and the failures the SDK retries without one, which sayretryable: false.fromthat has a reply-to sends, from the project's default sender. A stalled attachment stream fails withETIMEDOUTand is closed.nodemailer-absent.spec.tsloads the builtposthog-nodeandposthog-node/nodemailerthroughimportandrequire, withnodemailerunresolvable, and sends one message.nodemailer-process.spec.tsruns a script on the built package with a stalled attachment and checks the script keeps running once the send has started, until the send fails.types/nodemailer-transport.tscheckscreateTransport(createPostHogTransport(...)),sendMail({ posthog }), andinfo.messageId, and rejects an unknown or wrongly typedposthogoption.nodemailer-declarations.spec.tscompiles NodeNext.mtsand.ctsconsumers against the built declarations.X-PostHog-Integration: nodemailer/<version>, which_sending_clientfrom feat(messaging): record the sending client on transactional email sends posthog#130017 reads asnodemailer. Today's server is checked by a code search only: posthog master has no reader for the header. The launch train's live send against production sends this request to today's server.Spec divergence. The emails spec in sdk-specs doesn't define framework adapters. This entry point uses only
emails.send()and theintegrationoption from #5574. Against the shared adapter contract, it adds theunsupported_optionrefusal, and it maps open and click controls totrackinginstead ofcapture_engagement.Release info Sub-libraries affected
Libraries affected
Checklist
If releasing new changes
pnpm changesetto generate a changeset file🤖 Agent context
Autonomy: Human-driven (agent-assisted)
Built by Claude Code (Opus 5.5) test-first in an earlier #41 thread, and continued in place by its successor thread, which kept the commits and their authorship. A GPT-6.1 Sol design pass found one simplification: the mapper throws the refusal error itself, with no separate refusal type.
tracking.opensandtracking.clicks, withsensitivepassed through, nevercapture_engagementalongside themcategoryin scope?posthogkey insendMail(), notX-PostHog-*headers, which the transport refusessenderother thanfrom?unsupported_header, because Nodemailer doesn't put it in the envelope and PostHog can't send it{ messageId }onlyposthog?unsupported_optionretryable?posthog.idempotency_keyand when the SDK would retry; never without a key, upload network errors includedETIMEDOUTattachmentsarray?normalize()like Nodemailer's JSON and SES transports; the SDK refuses an oversized message after the read and before any requestETIMEDOUT?Mailercloses the app's streams on the failure, and its fetch ends a URL within its own time and size limits; the transport can't reach the file and URL streams without reimplementingnormalize()Transporttypes?Involvement: 0 grilling rounds, 1 design pass (GPT-6.1 Sol), 2 review panel rounds (fresh eyes on Claude; correctness, risk, design, anti-overengineering, sweep, and the Michael and SDK spec conformance perspectives on GPT-6.1 Sol; round 2 on the fixed lenses), 3 final reads (GPT-6.1 Sol), the PostHog Review bot's threads answered, red/green and cross-version proof captured.
🤖 Generated with Claude Code